/**
 * @addtogroup brd_can_rtx
 * brd_can_rtx
 * @{
 */
/**
 * @file brd_can_rtx.h
 * @brief CAN收发器板级层
 * @par 修改日志
 * <table>
 * <tr><th>Date         <th>Version <th>Author      <th>Description
 * <tr><td>2024-10-28   <td>1.0     <td>软件工程院  <td>创建初始版本
 * @par 示例
 * @code
 * 
  // 创建句柄
  Brd_THandle can_trx = Brd_CanTrxCreate(kBrd_CanTrxId0);

  /// 设置正常工作模式
  Brd_CanTrxSetCanfd(can_trx, False);       ///< 设置普通CAN模式
  Brd_CanTrxSetMode(can_trx, False);        ///< 设置正常模式
  Brd_CanTrxOpen(can_trx);                  ///< 打开CAN收发器
  UInt32 status;
  Brd_CanTrxGetStatus(can_trx, &status);    ///< 获取can收发器状态

  /// 设置休眠模式，指定报文唤醒
  Brd_CanTrxClose(can_trx);                 ///< 关闭CAN收发器, 然后设置属性
  Brd_CanTrxSetMode(can_trx, True);         ///< 设置休眠模式
  Brd_CanTrxSetBaudrate(can_trx, 500000);   ///< 设置波特率
  TCanData mask = 
  {
      .frame_type = 1,  ///< 表示只匹配ID字段, 不匹配数据字段
      .id = 0x0,        ///< ID掩码, 为0表示ID全匹配
      .id_type = 0,     ///< 标准ID
      .length = 0,
  };
  Brd_CanTrxSetRemoteWake(can_trx, 0x123, &mask); ///< 设置唤醒报文
  Brd_CanTrxOpen(can_trx); ///< 打开CAN收发器
 * @endcode
 * @copyright 杭州鸿泉物联网技术股份有限公司

 */

#ifndef _BRD_CAN_TRX_H_
#define _BRD_CAN_TRX_H_

#include <ofc_types.h>
#include "brd_common.h"
#include "can_def.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * 根据标识创建句柄
 * @param id: 标识, 参见[brd_def](@ref Brd_TCanIdTag)
 * @return 当返回值为非 NULL 时, 表示创建成功, \n
 *         当返回值为 NULL 时, 表示创建失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Brd_THandle Brd_CanTrxCreate(Int32 id);

/**
 * 释放句柄
 * @param handle: 句柄
 * @return 无返回值
 */
void Brd_CanTrxFree(Brd_THandle handle);

/**
 * 获取标识
 * @param handle: 句柄
 * @return 返回用于创建句柄的标识
 */
Int32 Brd_CanTrxId(Brd_THandle handle);

/**
 * 获取波特率
 * @param self: 对象实例指针
 * @param baudrate: 波特率; 未设置时, 获取默认值
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxGetBaudrate(Brd_THandle handle, UInt32 *baudrate);

/**
 * 设置波特率
 * @note 必须在 Brd_CanTrxOpen 之前调用
 * @param self: 对象实例指针
 * @param baudrate: 波特率
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxSetBaudrate(Brd_THandle handle, UInt32 baudrate);

/**
 * 设置CANFD模式
 * @note 必须在 Brd_CanTrxOpen 之前调用
 * @param self: 对象实例指针
 * @param is_canfd: 模式, True-支持CANFD模式, False-支持标准模式
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxSetCanfd(Brd_THandle handle, Bool is_canfd);

/**
 * 设置CAN远程唤醒
 * @note 必须在 Brd_CanTrxOpen 之前调用
 * @param self: 对象实例指针
 * @param can_id: 待匹配的CAN标识
 * @param mask: CAN帧掩码, 说明如下:
 *  当mask的frame_type为远程帧时, 只匹配can_id; 
 *      当mask的id字段中的位为1时, 表示该位是"无关位", 即收到报文中的位为0或1时, 都能匹配can_id的位.
 *      当mask的id字段中的位为0时, 收到报文的id位必须与can_id位相同, 才能生效.
 *  当mask的frame_type为数据帧时, 匹配can_id和mask的data字段.
 *      mask的data中的位为1时代表一个组, 因此如果length=8, mask的data字段最多同时有64个组.
 *      收到报文中的data位, 只要有一个位与mask的data位组相同, 就能匹配.例如:
 *      lenth = 1       | data[0].bit0   1   2   3   4   5   6   7
 *      mask            |            1   0   1   0   1   0   0   0
 *      recv            |            0   1   1   1   1   0   0   0 
 *      bit2和bit4都命中, 因此匹配成功.
 *  param,bus_index字段无效.
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxSetRemoteWake(Brd_THandle handle, UInt32 can_id, TCanData *mask);

/**
 * 获取工作模式
 * @param self: 对象实例指针
 * @param is_sleep: 模式, True-休眠模式, False-正常模式
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxGetMode(Brd_THandle handle, Bool *is_sleep);

/**
 * 设置工作模式
 * @param self: 对象实例指针
 * @param is_sleep: 模式, True-休眠模式, False-正常模式
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxSetMode(Brd_THandle handle, Bool is_sleep);

/**
 * 打开
 * @param self: 对象实例指针
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxOpen(Brd_THandle handle);

/**
 * 驱动关闭
 * @param self: 对象实例指针
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxClose(Brd_THandle handle);

/**
 * 获取状态
 * @note 必须在正常工作模式下获取, 休眠模式不支持.
 * @param self: 对象实例指针
 * @param status: 设备状态, 说明如下:
 *  status分为4个字段, 其中BIT31~24表示全局事件状态, BIT23~16表示系统事件状态,
 *  BIT15~8表示收发器事件状态, BIT7~0表示唤醒引脚事件状态.
 *  具体含义如下:
 *  - 全局事件状态:
 *      BIT27: 0-没有挂起的WAKE引脚事件,         1-有挂起的WAKE引脚事件
 *      BIT26: 0-没有挂起的收发器事件,           1-有挂起的收发器事件
 *      BIT24: 0-没有挂起的系统事件,             1-有挂起的系统事件
 *  - 系统事件状态:
 *      BIT20: 0-电池近期未上电,                 1-电池上电后, 设备已退出关断模式
 *      BIT18: 0-未检测到过温,                   1-检测到过温    
 *      BIT17: 0-未检测到SPI故障,                1-检测到SPI故障
 *  - 收发器事件状态:
 *      BIT13: 0-未检测到部分网络帧检测错误,      1-检测到部分网络帧检测错误
 *      BIT12: 0-CAN总线激活,                   1-CAN总线未激活
 *      BIT9:  0-未检测到CAN故障事件,            1-检测到CAN故障事件
 *      BIT8:  0-未检测到CAN唤醒事件,            1-检测到CAN唤醒事件
 *  - 唤醒引脚事件状态:
 *      BIT1: 0-未检测到WAKE引脚上的上升沿,      1-检测到WAKE引脚上的上升沿
 *      BIT0: 0-未检测到WAKE引脚上的下降沿,      1-检测到WAKE引脚上的下降沿
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxGetStatus(Brd_THandle handle, UInt32 *status);

/**
 * 触发本地唤醒
 * @note 立即使用WAKE引脚唤醒设备, 在正常工作模式下无效.
 * @param self: 对象实例指针
 * @return 当返回值 >= 0 时, 表示成功 \n
 *         当返回值 <  0 时, 表示失败, 参见[hcc_error_code_drv_brd.h](@ref Brd_TErrorCodeTag)
 */
Int32 Brd_CanTrxTriggerLocalWake(Brd_THandle handle);

#ifdef __cplusplus
}  ///< extern "C"
#endif

#endif /// _BRD_CAN_TRX_H_
/**
 * @} 
 */
